feat(otel): add structured trace-context types and execution-trace resolver - #685

Codex AI review

No actionable findings. Residual risk is limited to future integration of these currently unused trace-context types with the OTel plugins; this PR adds unit coverage only.

Reviewed commit e3f2437cf3751e147f6945757c114ddff26bd1ca. Workflow run

Claude AI review

No actionable findings. This PR adds foundational OpenTelemetry trace-context types (Sampling, ExtractedContext, ExecutionTraceContext, canonical_trace_id, derive_execution_root_span_id) with no consumers yet, matching the PR description.

Verified as correct:

• ID validity ranges match the OTel spec (128-bit trace IDs, 64-bit span IDs, all-zero rejected).
• derive_execution_root_span_id is deterministic (blake2b, replay-stable), namespaced distinctly from the Workflow and operation span-ID derivations, and guards the all-zero case with or 1.
• resolve trace-flag precedence (explicit SAMPLED/NOT_SAMPLED, else defer to root_sampled()) is consistent with its tests; the ... or 0 fallbacks in the complete-remote-parent and canonical_trace_id paths are unreachable given the validity guards and are harmless.
• No import cycle is introduced; frozen dataclasses and complete type annotations satisfy the repo's typing conventions.
• Test coverage is adequate for the new surface.

Residual test risk (not a defect, flagged for the follow-up PRs that wire these types):

• When a complete remote parent is present but ExtractedContext.sampling is UNDECIDED, resolve re-samples via root_sampled() rather than honoring the incoming trace's own sampling decision. This is untested against real backend headers and could produce partial traces if the backend does not populate sampling alongside a joined remote parent — worth confirming when the extractor that builds ExtractedContext lands.
• Minor: the module-level function canonical_trace_id is shadowed by the same-named int parameter of ExecutionTraceContext.resolve (execution_trace_context.py). No functional impact today, but a future edit to resolve that tries to call the function internally would silently bind the parameter instead; consider renaming one for clarity.

Reviewed commit e3f2437cf3751e147f6945757c114ddff26bd1ca. Workflow run